/*
 * Copyright (c) 2010, Katholieke Universiteit Leuven
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 
 *     * Redistributions of source code must retain the above copyright notice,
 *       this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright notice,
 *       this list of conditions and the following disclaimer in the documentation
 *       and/or other materials provided with the distribution.
 *     * Neither the name of the Katholieke Universiteit Leuven nor the names of
 *       its contributors may be used to endorse or promote products derived from
 *       this software without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/**
 * @addtogroup reconfiguration
 * @{
 */
/**
 * @defgroup introspection Introspection
 * @{
 */
/**
 * @file 
 * Header file for the local introspection functionality
 * @author 
 * Wouter Horré <wouter.horre@cs.kuleuven.be>
 */
#ifndef __LOOCI_INTROSPECTION_LOCAL_H__
#define __LOOCI_INTROSPECTION_LOCAL_H__

#include <stdbool.h>

#include "net/peers.h"
#include "events/eventtype.h"
#include "events/events.h"

/**
 * Get the components ids of the components with a given type.
 *
 * @param ctype The type of the components.
 * @param buffer A buffer where the ids of the components will be copied to
 * @param size Pointer to a variable that will hold the number of components in the buffer
 *             after the call. This variable should be initialized to the maximum number of
 *             components the buffer can hold.
 *
 * @return 'true' if successful, 'false' otherwise
 *
 * @note if the return value is false and *size > 0, the buffer was too small to hold all component ids.
 *       if the return value is false and *size == 0, another error occured.
 *       if the return value is true and *size == 0, there are no components with the given type.
 */
CCIF bool looci_intro_getcomponentids_by_type(char * ctype, u8_t * buffer, u8_t * size);

/**
 * Get the components ids of all components.
 *
 * @param buffer A buffer where the ids of the components will be copied to
 * @param size Pointer to a variable that will hold the number of components in the buffer
 *             after the call. This variable should be initialized to the maximum number of
 *             components the buffer can hold.
 *
 * @return 'true' if successful, 'false' otherwise
 *
 * @note if the return value is false and *size > 0, the buffer was too small to hold all component ids.
 *       if the return value is false and *size == 0, another error occured.
 *       if the return value is true and *size == 0, there are no components.
 */
CCIF bool looci_intro_getcomponentids(u8_t * buffer, u8_t * size);

/**
 * Get the type of a given component
 *
 * @param cid The id of the component
 * @param type A string buffer were the type will be copied to
 * @param maxsize The maximum size of the type the buffer can hold
 *
 * @return 'true' if successful, 'false' otherwise
 *
 * @note if the return value is false, type may still contain a truncated type string.
 */
CCIF bool looci_intro_getcomponenttype(u8_t cid, char * type, u8_t maxsize);

/**
 * Get the state of a component
 *
 * @param cid The component id.
 *
 * @return The state of the component. COMPONENT_STATE_NONE in case of error.
 */
CCIF u8_t looci_intro_getstate(u8_t cid);

/**
 * Get the interfaces of a component
 *
 * @param cid The component id.
 * @param buffer A buffer where the interfaces will be copied to
 * @param size Pointer to variable that will contain the number of interfaces in the buffer
 *             after the call. This should be initialized to the maximum number of interfaces
 *             the buffer can hold.
 *
 * @return 'true' if successful, 'false' otherwise
 * 
 * @note if the return value is false and *size > 0, the buffer was too small to hold all interfaces.
 *       if the return value is false and *size==0, an other error occured.
 *       if the return value is true and *size==0, the component has no interfaces
 */
CCIF bool looci_intro_getinterfaces(u8_t cid, looci_eventtype_t * buffer, u8_t * size);

/**
 * Get the receptacles of a component
 *
 * @param cid The component id.
 * @param buffer A buffer where the receptacles will be copied to
 * @param size Pointer to variable that will contain the number of receptacles in the buffer
 *             after the call. This should be initialized to the maximum number of receptacles
 *             the buffer can hold.
 *
 * @return 'true' if successful, 'false' otherwise
 * 
 * @note if the return value is false and *size > 0, the buffer was too small to hold all receptacles.
 *       if the return value is false and *size==0, an other error occured.
 *       if the return value is true and *size==0, the component has no receptacles.
 */
CCIF bool looci_intro_getreceptacles(u8_t cid, looci_eventtype_t * buffer, u8_t * size);

/**
 * Get the remote outgoing wires for an interface.
 *
 * @param eventtype The type of events the inteface produces.
 * @param cid The component that produces the events
 * @param buffer A buffer where the ids of the remote destination nodes will be copied to.
 * @param size A pointer to a variable that will contain the number of node ids copied to the
 *	       buffer after the call. This variable must be initialized to the maximum number of
 *	       component ids the buffer can hold.
 * 
 * @return 'true' if successful, 'false' otherwise
 *
 * @note if the return value is false and *size > 0, the buffer was too small to hold all node ids.
 *       if the return value is false and *size==0, an other error occured.
 *       if the return value is true and *size==0, the interface is not wired to a remote component.
 */
bool looci_intro_getoutgoingremotewires(looci_eventtype_t eventtype, u8_t cid, peer_id_t * buffer, u8_t * size); 

/**
 * Get the remote incoming wires for a receptacle.
 *
 * @param eventtype The type of events the remote interface produces.
 * @param cid The identifier of the destination component.
 * @param buffer A buffer where the information about the incoming wires will be written to.
 * @param size A pointer to a variable that will contain the number of incoming wires after the call. This variable
 *             must be initialized to the maximum number of incoming wires that the buffer can contain.
 *
 * @return 'true' if successful, 'false' otherwise
 *
 * @note if the return value is false and *size > 0, the buffer was too small to hold all incoming wires.
 *       if the return value is false and *size==0, an other error occured.
 *       if the return value is true and *size==0, there are no incoming wires for the receptacle.
 */
bool looci_intro_getincomingremotewires(looci_eventtype_t eventtype, u8_t cid, struct wire_from * buffer, u8_t * size);

/**
 * Get the local wires for an interface.
 *
 * @param eventtype The type of events the interface produces.
 * @param cid The component that produces the events
 * @param buffer A buffer where the ids of the destination components will be copied to.
 * @param size A pointer to a variable that will contain the number of component ids copied to the
 *             buffer after the call. This variable must be initialized to the maximum number of
 *             component ids the buffer can hold.
 * 
 * @return 'true' if successful, 'false' otherwise
 *
 * @note if the return value is false and *size > 0, the buffer was too small to hold all component ids.
 *       if the return value is false and *size==0, an other error occured.
 *       if the return value is true and *size==0, the interface is not wired to a local component.
 */
CCIF bool looci_intro_getlocalwires(looci_eventtype_t eventtype, u8_t cid, u8_t * buffer, u8_t * size);
#endif
/** @} */
/** @} */

